<!DOCTYPE html>
<!--
File:      execute.html
Author:    Henry Feild
Date:      March 2013
Purpose:   Documents how to develop and use a CrowdLogger Remote Module.

%%COPYRIGHT%%

Version: %%VERSION%%
-->
<html>
<head>
    <script src="js/external/jquery.min.js"></script>
    <script src="js/content-page.js"></script>
</head>
<body>
<div class="toc">
    <h2>Contents</h2>
    <ul>
        <!-- <li><a href="#execute">Using a CrowdLogger Remote Module</a> -->
        <li><a href="#execute:which-publishing-method">Which publishing method</a>
        <li><a href="#execute:crowdlogger-server">Publish on a CrowdLogger server</a>
        <li><a href="#execute:self-publish">Self publish</a>
    </ul>
</div>

<h1>Publishing a CrowdLogger Remote Module</h1>

<a name="which-publishing-method"></a>
<h2>Which publishing method</h2>

<p>
You have two options for making your CLRM available: publish it on the CrowdLogger server or self publish. Use the latter when developing or when you'd rather not wait to have your CLRM placed on the CrowdLogger server. 
</p>

<a name="crowdlogger-server"></a>
<h2>Publish on a CrowdLogger server</h2>
<p>
If you want to publish your CLRM to the UMass CrowdLogger server, then send your CLRM package, along with a description of who you are and what your app does to <a mailto="crowdlogger@crowdlogger.org">crowdlogger@crowdlogger.org</a>.
</p>

<p>
If you are hosting your own instance of a CrowdLogger server, then follow these steps:
</p>
<ol>
    <li>navigate to the <tt>html/clrms/</tt> directory of your CrowdLogger server</li>
    <li>create a new directory for your CLRM (e.g., you might name this after the CLRM id)</li>
    <li>update the metadata for your package so that the <code>packageURL</code> and <code>logoURL</code> point to this location (use absolute urls)</li>
    <li>in the directory you just created, copy:</li>
    <ul>
        <li>the CLRM package</li>
        <li>a copy of the metadata stored in a file called <code>metadata.json</code></li>
        <li>the logo image for your CLRM if you have one</li>
    </ul>
</ol>

<a name="self-publish"></a>
<h2>Self publish</h2>
<p>
For this step, you will need some sort of server running. Python provides a nice built-in server, so use that if you do not have a full blown server like Apache running.
</p>

<h3>Step 1: Create a directory to house your CLRM</h3>
<p>
If you are using a web server, create a directory in a location that is accessible via your web server. If you do not have a web server, create a directory wherever you'd like, then start up a Python server in that directory with the command: <code>python -m SimpleHTTPServer 8080</code>
</p>

<h3>Step 2: Update your CLRM metadata</h3>
<p>
Each CLRM you plan to self publish in the location above should be updated such that the URLs point to that location. If using the Python server, use <code>localhost:8080</code> as the url base, followed by the name of your JSON package (for <code>packageURL</code>) or logo (for <code>logoURL</code>).
</p>

<h3>Step 3: Create a meta-metadata file</h3>
<p>
You need to create a JSON file that consists of key value pairs where there is one key for each CLRM that you would like to publish (the key should be its <code>clrmid</code>) and the value should be its metadata (as a JSON object). E.g.:
</p>

<pre class="prettyprint">
{
    "demo1": {
        "clrmid": "demo1",
        "name": "Demo 1",
        "version": "1.5",
        "categories": ["app"],
        "description": "A simple CrowdLogger Remote Module demonstration.",
        "packageURL": "http://localhost:8080/demo.json",
        "permissions": ["userdata", "ui", "storage"],
        "logoURL": "http://localhost:8080/demo.jpg",
        "minCLVersion": "2.0.2"
    }
}
</pre>
<p>
You can call this file whatever you want. For the purposes of this tutorial, I'll assume you've named it <code>clrms.json</code>.
</p>

<h3>Step 4: Copy your CLRMs to the directory from Step 1</h3>
<p>
For each CLRM you have listed in <code>clrms.json</code>, copy over the CLRM package. These should be named according to how they are referenced in the <code>packageURL</code> fields in the metadata/<code>clrms.json</code> file. If you have logos, copy them over to this directory, as well.
</p>

<h3>Step 5: Add your server URL to a CrowdLogger browser installation's repositories</h3>
<p>
Open up your browser that has CrowdLogger installed and go to Settings and add your URL, including the name of the file you created in Step 2, as a new repository. E.g., for the example above, I would add: <code>http://localhost:8080/clrms.json</code>.
</p>

<h3>Step 5: Load module</h3>
<p>
If you visit the Apps &amp; Studies page from the CrowdLogger Status page, you should now see your app in the library. You can force your CLRM to be reloaded from the URL if you are in developer mode (you can toggle this mode in the CrowdLogger Settings). If you have the CLRM installed, then hovering over the module's icon will produce a popup with an <code>Update</code>
button. Press that to download the current package from the repository.
</p>
</body>
</html>